home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Steal This CD
/
steal_this_cd.iso
/
Chapter 07 - Where the Hackers Are
/
virc200.exe
/
{app}
/
script.txt
< prev
next >
Wrap
Text File
|
2003-05-16
|
60KB
|
1,392 lines
Scripting documentation for ViRC 2.0 and later
----------------------------------------------
This file describes changes to the Versus language as documented in
versus.txt and ovs.txt.
The Versus language is based on ViRCScript, which was created by
Adrian Cable for Visual IRC '96. Among the differences are enhanced
support for objects, toolbars, lists and arrays. Also, instead of all
scripts running in the same environment, a separate interpreter is
created for each server, which affects object event handlers.
Last updated 13 Apr 2001 for 2.0pre6 - see changes.txt for later additions.
Variables
=========
$scripthost
Contains "ViRC".
$ver
Contains a description of the current version of the client, such as
"ViRC 2.0".
$build
Contains an integer describing the current version of the client, such
as 200.
$prebuild
Contains the current prerelease number, or 0 if this is a release version.
$N
Contains the nick of the current server or DCC chat window. Undefined when
the script is running on the global interpreter.
$server
Describes the current server: either "global", "unconnected", or the
server's name for itself.
Commands
========
Exit:
Quits the client.
NewServerWindow:
Creates a new server connection window.
ShowClientSetup:
Displays the client configuration window.
ShowDCCList:
Toggles display of the DCC list window.
ShowNotifySetup:
Displays the notify list configuration window.
ShowServerList:
Displays the server list window.
ShowScriptLog:
Brings the script log window to the front, if ViRC was started with the
-scriptlog parameter.
Connect:
Causes the current server window to connect.
Disconnect:
Causes the current server window to disconnect.
Server <server name>:
Connects the current server window to another IRC server.
<server name> may take the form of either 'irc.cris.com',
'irc.cris.com:6665', or 'irc.cris.com:6665%password'. If a port is not given,
the default is 6667.
This command will attempt to match a server list entry by looking for an
entry with the supplied server name, then the supplied host and port, and
finally the supplied host and any port. For example, a server entry named
"prison" with the hostname irc.prison.net and port 6670 can be matched by
'/server prison', '/server irc.prison.net:6670', or just
'/server irc.prison.net'. '/server prison:6667' will override the entry's port
and connect to irc.prison.net on port 6667, but it will use all the other
settings from the entry.
If <server name> is prefixed by an asterisk, ViRC will not change the
supplied hostname or port, and it will not match a server list entry by the
server name. For example, '/server *prison' will connect to a host named
"prison" on port 6667, even though the server entry named "prison" specifies
a different host and port.
Quote <text>:
Raw <text>:
Sends the text directly to the server. Quote and Raw are equivalent.
Msg <target> <text>:
Sends the text to <target> as a private message. <target> may be an IRC
nickname or channel name, or the name or number of a DCC chat preceded by
an equal sign (e.g., '=myfriend'). If you want to send text to a channel,
you should use Say instead.
If you override Msg, your alias will be called for text entered in query
and DCC chat windows.
Say [channel] <text>:
Sends the text to <channel>. If <channel> is omitted, the text is sent to
the currently active channel.
Notice <target> <text>:
Sends the text to <target> as a private or channel notice. <target> may be
an IRC nickname or channel name.
Quit [message]:
Disconnects the current server window with a quit message. If <message> is
omitted, a default message will be supplied.
TextOut [-nohilite] [> window] <color> <text>:
Displays text in a window, using a specific color. If a right angle bracket
follows the command name, the next word specifies the window (a channel
name, query name, DCC chat name preceded by an equal sign, or '.' for the
server window). If the bracket and window name are omitted, the text is
displayed to the currently active window, or if the active window belongs
to a different server, the text is displayed in the server notices window
of the current server.
If the -nohilite option is given and the target window is not active, the
corresponding window tab will not be highlighted. Use this for messages that
do not demand the user's attention.
If <window> is specified but does not refer to an existing window, the text
will not be displayed unless <window> is an appropriate name for a query
window, in which case a query window will automatically be created.
If <window> is a comma-separated list of window names, each one will be tried
in order: query1,query2,#channel will first try query1, then query2, then
#channel, and display in the first window that exists. If none of them exist,
the text will not be shown unless the last name refers to a query window, in
which case it will be created automatically.
<window> can also be an object handle prefixed by a percent sign to display
the text in a TRichEdit or TMonkeySex control that has been created with OVS.
If the handle is invalid or does not refer to a control of the correct type,
no text is displayed.
If the text contains any \L characters (ASCII 10), the enclosed text will be
displayed in ecHyperlink and underlined, and will act as a hyperlink when
double-clicked: \Lwww2.foo.com\L. ViRC will add these automatically, so a
script should only add \L when it knows that the client won't recognize the
enclosed text as a link (but the client must be able to handle it as a link
once it's clicked!). Double-clicking the link runs 'WebHyperlink <text>'; if
WebHyperlink is an alias, it can use the $C variable to determine which
channel the link was in. Any other attribute codes inside \L will terminate
the link.
If the text contains any \S characters (ASCII 13), the enclosed text will be
displayed in ecScriptLink and will run a command when clicked or double-
clicked: \Schannel:#ViRC\S. Note that the text must contain a colon, and that
the text before the colon determines which command will be run; the example
will run a command called click_channel (the "channel:" will not be visible
to the user). The command will receive the word 'single' or 'double' as its
first parameter (depending on whether it was clicked once or twice), and the
text after the colon as its remaining parameters. You can pass additional
parameters at the beginning by putting spaces in the text:
'\Schannel #ViRC:Click here to join #ViRC.\S' will run this when clicked:
click_channel #ViRC single Click here to join #ViRC.
This command can use $C to determine which channel the link was in. Any other
attribute codes inside \S will terminate the link.
TextOutBitmap [-nohilite] [> window] <color> <bitmap> <text>:
Displays text in a window, prefixed by a bitmap. <bitmap> can either be
a filename (which must be all one word) or an integer returned by the
$bitmap() function.
FlushBitmapCache:
Empties the internal bitmap cache. Use this if a bitmap is changed after
first being loaded and you want to display the new one.
FlushBitmapCache <filename>:
Removes only the specified file from the bitmap cache.
CTCP <target> <text>:
Sends the text to <target> as a CTCP (Client-To-Client Protocol) request.
RCTCP <target> <text>:
Sends the text to <target> as a CTCP reply.
Ver <target>:
Sends a CTCP version request to <target>. This is exactly equivalent to
'CTCP <target> VERSION'.
Ping <target>:
Sends a CTCP ping request to <target>. This is equivalent to
'CTCP <target> PING $*mtime()'.
Mode <channel> <mode change>:
Attempts to change the channel mode.
Umode <mode change>:
Attempts to change your user mode. This is equivalent to
'Mode $N <mode change>'.
Names <channel>:
Retrieves a list of names of users on the channel.
Who <channel>:
Retrieves a detailed list of users on the channel.
OnServer <id> <command>:
Executes a command on another server. <id> is the index of the server's
entry in $ServerList(), which is also the number that appears in the server
window's title bar. If <id> is 0, the command will be executed on the
global interpreter.
Load <filename> [parameters]:
Loads a text file and executes it as script code. If the filename contains
spaces, surround it with double quotes. The file will be passed
Topic [channel] [new topic]:
Attempts to change the topic on a channel. If <channel> is omitted, the
current channel will be used. If <new topic> is omitted, the current topic
will be retrieved.
Kick [channel] <nick> [reason]:
Attempts to kick someone from a channel. If <channel> is omitted, the
current channel will be used. If <reason> is omitted, a default reason will
be provided by the IRC server.
KB [channel] <nick> [reason]:
Attempts to ban and kick someone from a channel. If <channel> is omitted,
the current channel will be used. If <reason> is omitted, a default reason
will be provided by the IRC server.
Ban [channel] <nick>:
Attempts to ban someone from a channel. If <channel> is omitted, the current
channel will be used.
Part [channel]:
Leaves the channel. If <channel> is omitted, leaves the current channel.
Query <nick> [message]:
Creates a new query window for <nick>. If <message> is specified, it will be
sent (via 'Msg <nick> <message>') as soon as the window is created.
AddToIAL <nick> <address>:
Adds the given nick and address to ViRC's IAL (Internal Address List), for
use with $getaddress().
RemoveFromIAL <nick>:
Removes the given nick from the IAL.
Me [channel] <text>:
Sends the text to the channel as a CTCP ACTION. If <channel> is omitted, the
action is sent to the currently active channel.
Desc <target> <text>:
Sends the text to <target> (a channel, nickname, or DCC chat name preceded
by an equal sign) as a CTCP ACTION. If you want to send an action to a
channel, you should use Me instead.
If you override Desc, your alias will be called when /me is used in a query
or DCC chat window.
MenuHint <name> on <tree> = <text>:
Sets a hint for a menu item. The hint will be displayed in the status bar of
the main ViRC window while the menu item is highlighted.
DCC Send <nick> [filename]:
Sends the file to <nick> using the DCC protocol. If <filename> is omitted, a
standard file dialog box will appear and allow the user to choose a file.
If the other person is using a client that supports it, you should use TDCC
instead.
DCC TSend <nick> [filename]:
TDCC Send <nick> [filename]:
Sends the file to <nick> using the Turbo DCC protocol. If <filename> is
omitted, a standard file dialog box will appear and allow the user to choose
a file. DCC TSend and TDCC Send are equivalent.
Turbo DCC is not supported by all clients. However, it is supported by BIRC,
PIRCH, XiRCON, and BitchX.
DCC Accept [filename]:
When used in an <OnDCCRequest> event, automatically accepts the request. If
the request is a file transfer and <filename> is specified, the file will be
saved with that name. If the file already exists, it will be overwritten.
DCC Reject:
When used in an <OnDCCRequest> event, automatically cancels the request.
DCC Resume <offset> [filename]:
When used in an <OnDCCRequest> event, automatically accepts the request. If
the request is a file transfer and <filename> is specified, the file will be
saved with that name. If the file already exists, the transfer will be
resumed from the specified offset.
DCC Request <type> <nick> <user@host> <params>:
Adds a DCC request to the DCC list window and runs the <OnDCCRequest> event
for it. <type> can be either CHAT, SEND, or TSEND. If <type> is CHAT,
<params> is two words: the IP address and the port. If <type> is SEND or
TSEND, <params> is four words: the filename, IP address, port, and file
size. If the filename contains spaces, it should be surrounded by double
quotes. If <type> is SEND (but not TSEND), the file size is optional.
Min <window>:
Max <window>:
Restore <window>:
Close <window>:
Show <window>:
Hide <window>:
Minimizes, maximizes, restores, closes, shows, or hides the window.
<window> can also be !Main to operate on the main ViRC window, except for
Show and Hide. Note that when you click the window's minimize button, the
window is actually hidden, not minimized.
SetInputLine <window> <text>:
Sets the contents of <window>'s input line.
Clear [window]:
Clears the output display of the given window. If <window> is omitted,
the current window's output will be cleared.
WebHyperlink <URL>:
Opens the URL using your default web browser.
Notify [nicks]:
Modifies the notify list. <nicks> is a space-separated list of nicks. Each
nick is added to the list, or removed if it is prefixed with a minus sign.
For example, 'Notify foo -bar -baz' would add foo, remove bar, and remove
baz. If <nicks> is omitted, the current notify list is shown.
FireEvent [-one] <name> [args]:
Runs the event with the given name, using <args> as parameters. Only events
whose masks match <args> will run. The first word of <args> will be passed
in as $0, and so on. <name> may contain wildcards, in which case all the
events with matching names and masks will be fired. If the -one option is
given, only the most specific matching event will be fired.
FireMenuItem [> channel] <item> on <tree> [= parameters]:
Runs the specified menu item handler. If the angle bracket and <channel> are
specified, $C will be set to <channel>; otherwise, it will be set to the
active window's name. If the equal sign and <parameters> are specified, the
menu item will receive <parameters> as $1-. $0 will be set to the item's
name prefixed with a '!'.
SetUserField <nick!user@host> <fieldname> <data>:
Associates the string <data> with the given user mask and field. <fieldname>
can be any word, but you should limit the number of different fields to
save space.
DelUserField <nick!user@host> <fieldname>:
Deletes the user list entry for the given user mask and field. Only the
specific entry for this mask will be removed; using DelUserField with the
mask '*!*@*.foo.com' will not remove an entry for '*!user@ppp*.foo.com'.
Log Open <window>:
Begins logging in the named window.
Log Close <window>:
Ends logging in the named window.
DNS <hostname/ip/nickname>:
Consults your nameserver to translate a hostname to an IP address or vice
versa, then displays the results. This will block script execution while
waiting for the DNS reply, but won't freeze the client.
If the parameter contains no dots and doesn't start with a number, it
will be treated as a nickname, and looked up with $getaddress(). To
prevent this, prefix the hostname with a *: /dns *localhost
Cycle <channel>:
Leaves and rejoins a channel without closing its window.
Asay <text>:
Says the text to every channel on the current server.
Ame <text>:
Sends the text as an action to every channel on the current server.
SimulateServerData <text>:
Fires internal and user-defined events as if <text> had just arrived from
the server. The events are fired immediately, even if there is unprocessed
text in the actual server socket buffer.
Kill <nick> <reason>:
Boots <nick> off the IRC network if you are an IRC operator.
Away [reason]:
Marks you as away for the given reason; this text will appear in your
/whois listing and when someone sends you a private message. If <reason>
is omitted, you will no longer be marked as away.
UnEvent <name>:
Deletes the event with the given name, if one exists.
SetServData <server name> <text>:
Sets the 'scriptdata' field of a server entry.
SetNetData <network name> <text>:
Sets the 'scriptdata' field of a network entry. <network name> must be
quoted as a list entry, since it can contain spaces or be an empty string
(for the 'no network' entry).
AddScriptControl <area> <type> <caption> <name> [options]:
Creates a new control in either the client setup window or the server list
for scripts to easily maintain their settings. The value of the control can
be changed by the user and the changes will automatically be saved.
<area> determines where the control appears and how the values are stored. It
can be either "config" (to appear in client setup), "network" (to appear on
the network page of the server list), or "server" (to appear on the server
page of the server list). "config" controls are saved as a client-wide
setting and can be manipulated with SetSetting and $getsetting(); "network"
and "server" controls are saved with each network or server and can be
manipulated with SetNetSetting/$getnetsetting() and SetServSetting/
$getservsetting().
<type> determines what kind of control appears. Possible values are "edit",
"check", "radio", and "button". Note that "button" controls simply run a
command; there is no data in the control for the user to edit. A button could
be used to bring up an OVS dialog box with more settings, for example.
<caption> is the string that will be displayed on the control (for a check
box or button) or as a label next to the control (for an edit box or radio
buttons). It should be quoted as a list item.
<name> is the name of the field used to manipulate the control's value in
$getsetting() and so on, unless the control is a button, in which case it is
the name of the command used to implement the button. The command will be
called with $1 as "click" when the button is clicked. The client will also
call it as a function with $1 as "display" when it wishes to retrieve a
string that will appear to the right of the button (when the form containing
the button is shown, and after the button is clicked); return a string in
$fresult, or return an empty string if none is appropriate.
The interpretation of <options> depends on the control type. For radio
buttons, <options> should be a list of strings (each quoted as list items)
that will be used as captions of the radio buttons. One button will be
created for each string in this list, and the value of the control will be a
number from 0 to one less than the number of buttons. For edit boxes,
<options> can be "password" if the characters typed in the box should appear
onscreen as asterisks. For check boxes, <options> can be "transparent" if the
user should be allowed to set it to greyed, rather than all the way checked
or unchecked (in which case the value will be 2). <options> has no meaning
for buttons.
DLL <filename> <function> [data]:
Loads the DLL specified by <filename>, and calls <function> with the
parameter <data>. If <data> is omitted, an empty string is passed. The
calling conventions are described in vircdll.txt.
Exec <filename> [parameters]:
Executes the file, optionally passing a parameter string. This is just like
typing the filename and parameters into the Run dialog box - it will open
a program, document, or URL.
Timer [name] <seconds> <repeats> <command>:
Creates a new timer called <name>, waiting <seconds> seconds, repeating
<repeats> times, and running <command>. If <name> is omitted, a unique name
will be generated. If <repeats> is 0, the timer repeats forever. <command>
will not be evaluated before it is run; if it should be, prefix it with Eval.
Timer names are shared across all servers, and must not start with a digit.
If a timer called <name> already exists, it will be deleted first.
MTimer [name] <millisecs> <repeats> <command>:
Same as Timer, but the delay is given in milliseconds (1/1000 second) instead
of seconds.
Timers:
Timers all:
Displays a list of all timers running on the current server, or on all
servers if 'timers all' is used.
UnTimer <name>:
Deletes the timer called <name>.
Functions
=========
$NewServerWindow():
Creates a new server window and returns its ID for use with OnServer.
$StrTrim(<text>):
Returns <text> after removing a leading colon (if present), then removing
any leading or trailing control-A characters.
$NickTrim(<text>):
Returns <text> after removing any leading nickname flags (@, %, or +).
$IsChannel(<text>):
Returns 1 if <text> could be the name of a channel, or 0 if not. ViRC
considers any string beginning with a # or & to be a legal channel name.
$NickList(<channel>):
Returns a list of all the nicknames on <channel>, or the null string if you
aren't on that channel.
$OpList(<channel>):
The same as $NickList(), but only returns the names of channel operators
(which are flagged with an @ in the channel window's nick list).
$VoiceList(<channel>):
The same as $NickList(), but only returns the names of channel voices
(which are flagged with a + in the channel window's nick list).
$HalfOpList(<channel>):
The same as $NickList(), but only returns the names of channel half-ops
(which are flagged with a % in the channel window's nick list).
$PeonList(<channel>):
The same as $NickList(), but only returns the names of peons (users who are
not ops, voices, or half-ops).
$IsOn(<nick> <channel>):
Returns 1 if <nick> appears in $NickList(<channel>), or 0 if not.
$IsOp(<nick> <channel>):
Returns 1 if <nick> appears in $OpList(<channel>), or 0 if not.
$IsVoice(<nick> <channel>):
Returns 1 if <nick> appears in $VoiceList(<channel>), or 0 if not.
$IsHalfOp(<nick> <channel>):
Returns 1 if <nick> appears in $HalfOpList(<channel>), or 0 if not.
$GetMode(<channel>):
Returns the mode string for <channel>, or an empty string if the channel
is not open. This string includes parameters, such as "+stl 15".
$GetTopic(<channel>):
Returns the topic string for <channel>, or an empty string if the channel
is not open.
$GetKey(<channel>):
Returns the key for <channel>, or an empty string if the channel is not
open or does not have mode +k set.
$GetLimit(<channel>):
Returns the user limit for <channel>, or 0 if the channel is not open or
does not have mode +l set.
$GetWindowId(<window>):
Returns a number that uniquely identifies the specified window. These
numbers are unique among all server windows for the client, all DCC chat
windows for the client, and all channels and query windows for the current
server window. For server windows and DCC chats, this number appears in the
title bar. For other window types, this number is not visible to the user.
$ChannelList():
Returns a list of all the channel windows for the current server.
$ServerList():
Returns a list of all the server windows. The index of each item in this
list is the number that appears in the server window's title bar and is
returned by $GetWindowId(). The first element is "global", and any spaces
between server windows are "destroyed".
For example: Suppose you create a server window and do not connect it. Then
you create another and connect it to irc.concentric.net. $ServerList() will
return "global unconnected irc.concentric.net:6667". Now suppose you close
the first server window, leaving the second one connected. $ServerList()
will return "global destroyed irc.concentric.net:6667".
$CurrentServer():
Returns the index of the current server in the list returned by
$ServerList(), or 0 if the function is called from the global interpreter.
$IsQuerying(<nick>):
Returns 1 if there is a query window open for <nick> on the current server,
or 0 if not.
$QueryList():
Returns a list of all the query windows for the current server.
$IsDCCChatting(<nick>):
Returns 1 if there is a DCC chat window open for <nick>, or 0 if not.
$DCCChatList():
Returns a list of all the DCC chat windows open on all server windows (since
DCC chat works independently of the server).
$DCCChatNick(<id>):
Returns the nick on the other end of the specified DCC chat, or the empty
string if there is no such DCC chat. <id> can be a number, a nick, or a
window name.
$GetAddress(<nick>):
Returns the address (user@host) of <nick>, or 'unknown@unknown' if there is
no such nick on IRC. This function will read the address out of the IAL if
it has been added with AddToIAL.
$IsInIAL(<nick>):
Returns 1 if <nick> is in the current server's IAL, or 0 if not.
$EncodeIP(<dotted ip>):
Returns <dotted ip> converted into an integer in network byte order. This is
useful for sending DCC requests.
$DecodeIP(<numeric ip>):
Returns <numeric ip> converted into a dotted IP address. This is useful for
displaying an incoming DCC request.
$AliasList():
Returns a list containing the name of every alias that has been added. This
can also be retrieved with the GetAliasList method of TStringList.
$EventList():
Returns a list containing the name of every event that has been added. This
can also be retrieved with the GetEventList method of TStringList.
$EventMask(<event name>):
Returns the given event's activation mask.
$EventExists(<event name>):
Returns 1 if the event exists, or 0 if not.
$GetMenuHint(<name> on <tree>):
Returns the given menu item's hint message.
$mIRCColor(<num>):
Returns the RGB value of the mIRC color specified by <num>, or 0 if the
number is out of the range 0..15.
$ActiveWindow():
Returns the window name of the currently active child window, or . if there
is no active child window or the active window belongs to another server.
$ActiveServer():
Returns the server ID number of the server that owns the active child
window, or 0 if there is no active child window or the active child is a
DCC chat window.
$Bitmap(<filename>):
Loads a .bmp image into the internal cache and returns a unique integer.
If the file has already been loaded, the same integer will be returned,
unless FlushBitmapCache has been called in the meantime.
$UhostToMask(<user@host>):
Generates a ban mask that matches the given user@host, of the form
*!*user@*host.
$NickToMask(<nick>):
Looks up the nick's address using $GetAddress(), then generates a matching
ban mask. If the nick's address cannot be found, a mask of the form
nick!*@* is returned.
$Notify():
Returns the current notify list as a space-separated list of nicks.
$Notify(<nick>):
Returns 1 if the nick is in the notify list and currently signed on (as far
as ViRC knows), or 0 otherwise.
$TimeConnected():
Returns the number of seconds the current server window has been connected,
or 0 if the server is unconnected.
$GetSetting([path] <name>):
Reads a setting from ViRC's registry key. If <path> is specified, it is a
space-separated list of keys to traverse: for example,
$GetSetting(Notify Interval).
ViRC saves its settings in:
HKEY_CURRENT_USER\Software\MeGALiTH Software\Visual IRC 2.
$GetUserField(<nick!user@host> <fieldname>):
Retrieves the string that has been associated with the given user and field,
or an empty string if no entry can be found. The most specific matching
entry that exists for that field will be used: for example, calling this
function for joe!user@ppp5.foo.com might return the string associated with
*!user@ppp*.foo.com.
$UserFieldList([fieldname]):
If <fieldname> is omitted, returns a list containing every field in the user
list; otherwise, returns a list containing every nick!user@host mask with
an entry in the given field.
$IdleTime():
Returns the number of seconds that have passed since data was last sent to
the server.
$ServerHost():
Returns the hostname:port used to connect to the server, or an empty string
if there is no server connection.
$GetPath():
Returns the path where the ViRC executable is located, including the
trailing backslash.
$IsLogging(<window>):
Returns true if the named window is currently logging.
$DNS(<hostname/ip/nickname>):
Consults your nameserver to translate a hostname to an IP address or vice
versa, then returns the results (or an empty string if the attempt failed).
This will block script execution while waiting for the DNS reply but not
freeze the client.
If the parameter contains no dots and doesn't start with a number, it
will be treated as a nickname, and looked up with $getaddress(). To
prevent this, prefix the hostname with a *: $dns(*localhost)
$IsIP(<text>):
Returns true if <text> is a valid numeric IP address. Note that strings like
'5' and '127.1' are valid IP addresses.
$SelectServer():
Displays the server list window so the user can choose a server entry by
double-clicking it, or selecting it and pushing OK. The return value is the
selected entry's server name, or an empty string if the user cancels.
$SelectNetwork():
Displays the server list window so the user can choose a network entry. The
return value is the selected entry's network name, or an empty string if the
user cancels or selects 'no network'.
$ServerID():
Returns the server name of the server entry currently being used, or an
empty string if there is none.
$NetworkID():
Returns the name of the network entry currently being used, or an empty
string if there is none.
$GetServSetting([server name] <setting name>):
Looks up a setting using the server entry, network entry, and global
configuration. If <server name> is supplied, the entry by that name will be
used instead of the currently active entry. Boolean settings are returned
as either 0 or 1. The available settings are:
nicklength (int), modeargs (int), defnicks (str), ident (str),
realname (str), atchan (bool), multinicks (bool), hostname (str),
network (str), password (str), scriptdata (str).
'defnicks' returns a list of nicks, in order: server-specific nicks,
network-specific nicks, and global default nicks. Each nick is quoted as a
list item. 'network' returns the name of the network associated with the
server.
An empty string will be returned if the setting is invalid, or if a server
name is given but no entry exists by that name.
$GetNetSetting([network name] <setting name>):
Looks up a setting using the network entry and global configuration. If
<network name> is supplied, the entry by that name will be used instead of
the currently active entry. Return values and available settings are the
same as above, except that 'defnicks' only returns network-specific and
global nicks, and these settings are not available: hostname, network,
password.
$PasswordQuery(<text>):
Shows a dialog box requesting a password from the user. This works just
like the $?= pseudo-function, but the password is masked with asterisks as
it is entered. If <text> contains a vertical bar, the text to the right of
it will be used as the default value (which is returned if the user
cancels): $passwordquery(Enter your password:|shazam)
$GetInputLine(<window>):
Returns the contents of <window>'s input line.
$StripAttrs(<text>):
Removes attribute codes (bold, italic, color, etc.) from <text> and returns
the plain text.
$StripLinks(<text>):
Removes hyperlinks (\Lfoo\L) and script links (\Scmd:foo\S), leaving
attribute codes alone.
$DLL(<filename> <function> [data]):
Loads the DLL specified by <filename>, calls <function> with the
parameter <data>, and returns the result. If <data> is omitted, an empty
string is passed. The calling conventions are described in vircdll.txt. If
the DLL function does not return a value, $DLL() returns an empty string.
$Timer([name] <seconds> <repeats> <command>):
Creates a new timer called <name>, waiting <seconds> seconds, repeating
<repeats> times, and running <command>. If <name> is omitted, a unique name
will be generated. Returns the name of the new timer.
If <repeats> is 0, the timer repeats forever. <command> will not be
evaluated before it is run; if it should be, prefix it with Eval.
Timer names are shared across all servers, and must not start with a digit.
If a timer called <name> already exists, it will be deleted first.
$MTimer([name] <millisecs> <repeats> <command>):
Same as $Timer(), but the delay is given in milliseconds (1/1000 second)
instead of seconds.
$TimerExists(<name>):
Returns true if a timer called <name> exists.
$TimerList([serverid]):
Returns a list of all timers running on the identified server, or on all
servers if <serverid> is omitted.
$GetTimer(<name>):
Returns a string of the form "interval repeats command", where interval is
given in milliseconds and repeats is the number of times the timer will be
called again. Returns an empty string if no timer called <name> exists.
$LocalNick(=<ID>):
Returns your nickname on the specified DCC chat connection.
$RemoteNick(=<ID>):
Returns the remote user's nickname on the specified DCC chat connection.
Menu Trees
==========
ViRC's menu trees are MT_MAINMENU, MT_SERVERPOPUP, MT_NOTIFYPOPUP,
MT_CHANNELTEXTPOPUP, MT_CHANNELNICKSPOPUP, MT_QUERYPOPUP, and MT_CHATPOPUP.
Each menu tree should be zero or more lines of the form:
<id> <hotkey> <magic> <depth> <name>
where <id> is a one-word identifier unique to this menu tree, <hotkey> is a
string of the form "Alt+X" (or "<none>" for no hotkey), <magic> is a number
describing the special behavior of this item, <depth> is how far this item is
indented (0 for a top-level item), and <name> is the caption of the menu item
(where an ampersand makes the next letter underlined, and && displays a single
ampersand).
For MT_SERVERPOPUP, <magic> can take the following values:
0 - item is always enabled
1 - enabled when connected to the server
2 - disabled when connected to the server
3 - item is always disabled
For MT_CHANNELTEXTPOPUP and MT_CHANNELNICKSPOPUP, it can take these values:
0 - item is always enabled
1 - enabled when opped on the channel
2 - disabled when opped on the channel
3 - item is always disabled
Currently, for the other trees <magic> is ignored and the item is always
enabled.
To assign code to a menu item, use the MenuItem block:
MenuItem M_CTCPVERSION on MT_CHANNELNICKSPOPUP
foreach ($i; $listfromwords($1-))
CTCP $i VERSION
endforeach
EndMenuItem
To assign code that is run when you double-click in the area, use the special
item ID "<DoubleClick>".
Menu item handlers run on the appropriate interpreter (the global interpreter
for MT_MAINMENU and MT_CHATPOPUP, and the server window's interpreter for all
others), and receive the following parameters and variables:
MT_MAINMENU, MT_SERVERPOPUP - none.
MT_NOTIFYPOPUP - all selected nicks in $1-, focused nick in $nick.
MT_CHANNELTEXTPOPUP - channel name in $C.
MT_CHANNELNICKSPOPUP - all selected nicks in $1-, focused nick in $nick,
channel name in $C.
MT_QUERYPOPUP - nick of query target in $1, $nick, and $C.
MT_CHATPOPUP - nick of DCC chat target in $1 and $nick, window name in $C.
Note that even though $1- might look like a list, it isn't a real list. The
elements might contain unquoted backslashes, which will cause list functions
and ForEach loops to give incorrect results. Use $listfromwords($1-) if you
need to access $1- like a list.
Events
======
Define an event using the syntax:
Event MyEventName "<event mask here>"
<code>
EndEvent
where MyEventName is a unique name for the event, and <event mask here> is a
standard VSInterp wildcard mask (using %, *, ?, and ¼). The event mask is
evaluated before it's added, which lets you use variables and backslash escapes
in the mask.
ViRC matches the event masks against text from the server (after removing any
trailing newlines and CTCP delimiters) and fires the most specific event that
matches. Each event is assigned a priority when it's created, which ViRC uses
to compare the specificness of events. Each *, or ¼ in the mask earns it zero
priority points, each % earns it one point, each ? earns it two points, and
each other character (or escaped wildcard) earns it three points. The mask with
the highest priority value is considered the most specific.
The word-break wildcard (¼, alt-0172) is useful for matching CTCP messages.
Since ViRC automatically removes trailing CTCP delimiters (\A), this mask will
match any CTCP VERSION request, but not CTCP VERSIONFOO:
% PRIVMSG % :\AVERSION¼
To run a specific event *in addition to* the less specific events, rather than
*instead of* them, use the FallThrough command:
Event AnyCTCP "% PRIVMSG % :\A*"
TextOut > . ecCTCP *** CTCP $strtrim($3) from $nick
EndEvent
Event CTCPVERSION "% PRIVMSG % :\AVERSION¼"
^RCTCP $nick VERSION I am proudly running $ver.
FallThrough
EndEvent
Script Hooks Called by ViRC
===========================
ViRC calls these script-defined events:
<OnStart* called when ViRC starts.
<OnClose* called just before ViRC exits.
<OnConnect* called when the IRC server acknowledges the connect (in
the 004 numeric). note that this is not fired
immediately after the socket connects.
<OnDisconnect* called when the IRC socket is closed.
<OnSocketOpen* called as soon as the IRC socket connects, before any
NICK or USER command is sent.
<OnCreateWindow* called when a new ViRC form is created. $0 is the form
type (TServerForm, TChannelForm, TDCCChatForm, or
TQueryForm) and $1 is the window name. if the form is a
DCC chat form, $1 contains the non-unique name (=nick)
and $2 contains the unique name (=123).
<OnNewDCCChatText* called when new text comes in on a DCC chat connection
(ViRC doesn't display the text by itself). $0 is the
nick, $1 is the window name, $2- is the text. only the
most specific matching event will be run, unless
FallThrough is used.
<OnDCCChatClosed* called when the remote end closes a DCC chat
connection. $0 is the nick and $1 is the window name.
<OnDCCRequest* called when a new DCC request is added to the list
(using the DCC Request command). see below.
<OnUserSetupOK* called when the user clicks the OK button to close the
client setup window and save changes.
<OnUserSetupCancel* called when the user clicks the Cancel button to close
the client setup window and discard changes.
<OnErrorConnecting* called when a socket error occurs before the socket is
connected. $0 is the error number and $1- is the
message.
<OnMyChanText* called by the built-in /say command to display text
that the user types into a channel. $0 and $C are the
channel, $1- is the text.
<OnMyPrivMsg* called by the built-in /msg command to display text
sent as a private message (other than in a query). $C
is the active window, $0 is the target nick, and
$1- is the text.
<OnMyNotice* called by the built-in /notice command to display text
sent as a notice. $C is the active window, $0 is the
target nick or channel, and $1- is the text.
<OnMyCTCP* called by the built-in /ctcp command to display CTCP
requests sent by the user. $C is the active window, $0
is the target nick or channel, and $1- is the text.
<OnMyRCTCP* called by the built-in /rctcp command to display CTCP
replies sent by the user. $C is the active window, $0
is the target nick or chanel, and $1- is the text.
<OnMyChanAction* called by the built-in /me command to display actions
the user performs in a channel. $C and $0 are the
channel, $1- is the text.
<OnMyPrivAction* called by the built-in /desc command to display
actions sent privately to another user. $C is the
active window, $0 is the target nick, and $1- is the
text.
<OnMyQueryText* called by the built-in /msg command to display text
that the user types into a query or DCC chat. $C and $0
are the window name (nick or =number), $1- is the text.
$N is set to the appropriate local nickname when called
for a DCC chat.
<OnMyQueryAction* called by the built-in /desc command to display actions
the user performs in a query. $C and $0 are the window
name, $1- is the text. $N is set to the appropriate
local nickname when called for a DCC chat.
All of these are called using wildcards, which means that <OnStart>,
<OnStart_MyScript>, and <OnStartFoo> will all be called. Events with names
surrounded by angle brackets will never be matched against text from the IRC
server.
Event masks are still matched when calling hooks. This event:
Event <OnCreateWindow_Servers> "TServerForm *"
<code>
EndEvent
will only run when a server form is created. However, with the exception of
<OnNewDCCChatText*, all matching events will be called (not just the most specific one).
ViRC will also call user-defined aliases:
WEBHYPERLINK <url> called when you double-click on a hyperlink.
CONNECT called when you click the server's connect button.
DISCONNECT called when you click the server's disconnect
button.
SAY <channel> <text> called when you type text in a channel, and by
/asay.
ME <channel> <text> called by /ame.
MSG <nick> <text> called when you type text in a query, and by
/query <nick> <text>.
MSG =<id> <text> called when you type text in a DCC chat window.
DESC <nick> <text> called when you use /me in a query.
DESC =<id> <text> called when you use /me in a DCC chat window.
CTCP <nick> <text> called by /ver and /ping.
QUIT <text> called by /server when you're already connected.
PART <channel> called when you close a channel window.
MODE <channel> <text> called by /ban and /kb.
KICK <channel> <nick> <text> called by /kb.
$NickToMask(<nick>) called by /ban and /kb.
Writing an <OnDCCRequest> Event
===============================
The <OnDCCRequest> event is fired by the DCC Request command after the request
is added to the DCC list. $nick, $user, and $host describe the nick and
user@host that were passed in the DCC Request command. The other parameters
are the type in $1 (CHAT, SEND, or TSEND), the encoded IP in $2, the remote
port in $3, the file size in $4 (or 0 if the size is unknown), and the filename
in $5-.
The event can run three special commands to automatically deal with the
request:
DCC Reject aborts the transfer immediately.
DCC Accept [<filename>] accepts the transfer immediately,
optionally renaming it.
DCC Resume <size> [<filename>] resumes the transfer immediately,
optionally renaming it. <size> is the
position to start resuming from, where
0 is the beginning of the file.
If the event doesn't run any of these commands, the request will stay in the
DCC list as usual.
Mappable Objects
================
For the form name in a $MapObject(form name[:control name]) call, you can use
a window name, or one of the special values:
!Main - main ViRC form
!UserSetup - configuration window
!About - about box
!DCCList - dcc list window
!Notify - notify setup window
!ScriptEditor - script editor
ViRC automatically adds the main form itself with object
handle 0. The mappable controls for each window type are:
Server windows (TServerForm)
----------------------------
ConnectBtn, DisconnectBtn (TToolbarButton97) - the buttons to connect to and
disconnect from the server.
ServerTxt (TEdit97) - the edit control containing the server name.
IALTimer (TTimer) - the timer that runs every minute to clean out the IAL.
NotifyTimer (TTimer) - the timer that sends ISON commands for the notify list.
ServerPopup, NotifyPopup (TPopupMenu) - the popup menus.
Output (TMonkeySex) - the box where scrolling text is displayed.
Input (TMemo) - the box where text is entered.
Notify (TListBox) - the notify nicks list.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
toolbars can be placed.
ServerToolbar (TToolbar97) - the toolbar containing ConnectBtn and
DisconnectBtn.
ServerSelectionToolbar (TToolbar97) - the toolbar containing ServerTxt.
WindowTab (TToolbarButton97) - the button corresponding to this window on the
tab bar.
Channel windows (TChannelForm)
------------------------------
ChannelTextPopup, ChannelNicksPopup (TPopupMenu) - the popup menus.
Output (TMonkeySex) - the box where scrolling text is displayed.
Input (TMemo) - the box where text is entered.
NickList (TListBox) - the channel nicks list.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
toolbars can be placed.
WindowTab (TToolbarButton97) - the button corresponding to this window on the
tab bar.
Query windows (TQueryForm)
--------------------------
QueryPopup (TPopupMenu) - the popup menu.
Output (TMonkeySex) - the box where scrolling text is displayed.
Input (TMenu) - the box where text is entered.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
toolbars can be placed.
WindowTab (TToolbarButton97) - the button corresponding to this window on the
tab bar.
DCC Chat windows (TDCCChatForm)
-------------------------------
ChatPopup (TPopupMenu) - the popup menu.
Output (TMonkeySex) - the box where scrolling text is displayed.
Input (TMenu) - the box where text is entered.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
toolbars can be placed.
WindowTab (TToolbarButton97) - the button corresponding to this window on the
tab bar.
Main form (TMainForm)
---------------------
MainMenu (TMainMenu) - the main menu.
StatusBar (TStatusBar) - the status bar. set the SimpleText property to change
the displayed text.
TopDock, BottomDock, LeftDock, RightDock (TDock97) - the docks where floating
toolbars can be placed.
Client setup form (TConfigForm)
-------------------------------
Use BCONV to get the code for this form.
Notify setup form (TNotifyForm)
-------------------------------
AddBtn, RemoveBtn (TButton) - the buttons to add or remove nicks.
NickList (TListBox) - a list box containing the nicks.
AutoNotify (TCheckBox) - the check box to enable automatic notify monitoring.
NotifyInterval (TEdit) - the edit box containing the number of seconds for
auto-notify.
OKBtn, CancelBtn (TButton) - the OK and Cancel buttons.
About box (TAboutForm)
----------------------
VersionLabel (TLabel) - a label containing the ViRC version.
OKBtn (TButton) - the OK button.
DCC list window (TDCCListForm)
------------------------------
DCCList (TListBox) - a list box containing all the active DCC requests.
however, it's an owner-draw control with no strings in its Items property,
so it isn't very scriptable.
AcceptBtn (TButton) - the button to accept the currently selected request.
CloseBtn (TButton) - the button to abort the currently selected request.
DCCListPopup (TPopupMenu) - the popup menu for the list box.
Script log form (TScriptLogForm)
--------------------------------
LogOutput (TMonkeySex) - the output pane.
LogPopup (TPopupMenu) - the right-click menu.
Modifications to OVS
====================
Methods added to TStrings
-------------------------
LoadFromEvent <eventname>
Fills the string list with the code of the named event.
SaveToEvent <eventname>
Creates or replaces an event with the given name, using the code from the
string list.
GetEventList
Fills the string list with the names of all defined events.
LoadFromMenuTree <treename>
Fills the string list with the named menu tree, in the same format as
described earlier.
SaveToMenuTree <treename>
Replaces the named menu tree using the description from the string list.
GetMenuTreeList
Fills the string list with the names of all available menu trees.
LoadFromMenuItem <itemname> on <treename>
Fills the string list with the code of the named menu item.
SaveToMenuItem <itemname> on <treename>
Replaces the named menu item using the code from the string list.
GetMenuItemList <treename>
Fills the string list with the names of all menu items on the named tree,
in seemingly random order.
New TTabbedForm class
---------------------
This is the same as TForm, but it creates a button on ViRC's tab bar. The
icon set with the form's Icon property is shown on the button.
Property:
TabCaption (string)
The text that appears on the button.
New TMonkeySex class
--------------------
This is the text scroller used on server/channel/query/DCC chat forms. (Blame
Gnowknaym for the name.)
Properties:
Align, Font, ParentFont, PopupMenu - standard.
Background (TColor)
The default background color.
BGBitmap (TBitmap)
The background image.
BGBitmapEnabled (boolean)
If true, the BGBitmap will be used; otherwise, the background color will
be used.
BufferSize (integer)
The number of scrollback lines to keep in memory.
Hyperlink (TColor)
The color to display hyperlinks in. (\Lfoo\L)
ScriptLink (TColor)
The color to display script links in. (\Scmd:foo\S)
Logging (boolean)
If true, the OnLogging event will be called for each line added.
Methods:
Clear
Erases all lines in the control.
PageDown
Scrolls down one page.
PageUp
Scrolls up one page.
Events:
OnClick, OnDblClick - standard.
OnCopyText
Called when the user selects some text and releases the mouse button. The
text is in $Text.
OnHyperlink
Called when the user double-clicks a hyperlink. The link text is in $Text.
OnScriptLink
Called when the user activates a script link. The associated command is in
$Command, the visible text is in $Text, the mouse button is in $Button,
the shift state is in $Shift, the client coordinates of the click are in
$X and $Y, and the screen coordinates are $ScreenX and $ScreenY.
OnLogging
Called when a new line is added and logging is enabled. The text is in
$Text.
New TSockets class for TCP connections
--------------------------------------
Create a TSockets object with the syntax $New(TSockets). These socket controls
will automatically use the specified SOCKS proxy settings for outgoing
connections, but listening for connections will not be possible over SOCKS.
If a socket error occurs and no OnErrorOccurred event handler is set, ViRC
will stop. If you don't plan to handle errors, you should at least set a
dummy event handler: @p $socket.OnErrorOccurred = Nop
('Nop' should not be confused with 'Nil', which unsets the event handler,
causing the error to go uncaught.)
Properties:
IPAddr (string)
The IP address or hostname to connect to.
Port (string)
The port number or name to connect to.
LocalIPAddr (string)
The IP address of the local host. May not be accurate if the host has
more than one address. Read-only.
RemoteIPAddr (string)
The IP address of the host on the other end of the connection. If the
connection is running through SOCKS, this will be the address of the
proxy server. Read-only.
SocketNumber (integer)
The number of the currently active connection.
MasterSocket (integer)
The number of the listening connection, if this socket object is listening.
Text (string)
Reading this property receives data from the socket (and removes the data
from the socket's input buffer); writing it sends data to the socket. This
should only be read from an OnDataAvailable event handler.
State (enumeration)
The socket's level of activity: sockDisconnected, sockDNS (looking up a
hostname), sockConnecting (waiting to connect to a host), sockConnected, or
sockRequestedSocks (waiting for a response from the proxy server).
Methods:
SConnect
Attempts to connect to the host in IPAddr and the port in Port. The
OnSessionConnected or OnErrorOccurred event will be called when the socket
connects or fails to connect.
SListen
Begins listening for connections on the socket using the port number in
Port.
SListenOnFreePort()
Picks an unused port number, begins listening for connections on that port,
then returns the port number.
SListenRange(<lowport> <highport>)
Attempts to listen on a free port between <lowport> and <highport>.
Returns the port number if successful, or 0 if unsuccessful.
SCancelListen
Cancels listening.
SAccept()
Accepts the connection and returns its connection number. Use this in an
OnSessionAvailable event.
SClose
Closes the connection. Does not call the OnSessionClosed event.
Send <text>
Sends the text without a newline.
SendCRLF <text>
Sends the text, followed by a carriage return and linefeed.
SetActiveConnection(<num>)
Sets the active connection (just like setting the SocketNumber property)
and returns the number of the previously active connection.
Events:
OnStateChanged
Called when the socket's State property changes. The new state is in the
$State variable.
OnDataAvailable
Called when data is available for reading. Read the Text property to get
the data. The socket number is in $Socket.
OnDataNeeded
Called when the socket is ready to write, either just after connecting or
after a previous write failed. Set the Text property or use the Send or
SendCRLF methods to write data. The socket number is in $Socket.
OnSessionAvailable
Called when a client is trying to connect to a listening socket. Call
SAccept to accept the connection.
OnSessionClosed
Called when the remote host has closed the connection. Call SClose here
to close down your side of the connection. The socket number is in $Socket.
OnSessionConnected
Called when an outgoing connection succeeds. The socket number is in
$Socket.
OnErrorOccurred
Called when a socket error occurs. If this is not handled, the application
will be stopped. The socket number is in $Socket, the error number is in
$Error, and the error message is in $Msg.
TSockets example
----------------
Outgoing connections:
// create socket
@ $socket = $new(TSockets)
// set up events
@p $socket.OnSessionConnected = SMTP_SESSIONCONNECTED
@p $socket.OnErrorOccurred = SMTP_ERROROCCURRED
// we'll use mail.myisp.com for SMTP (port 25)
@p $socket.IPAddr = mail.myisp.com
@p $socket.Port = 25
// connect
$socket.SConnect
// OnSessionConnected event handler
Alias SMTP_SESSIONCONNECTED
// send a message
// get email addresses
@l $to = $?="Enter an address to send mail to:"
@l $from = $?="Enter your return address:"
// SMTP identify to server (the socket is in $Sender)
$Sender.SendCRLF HELO vircmail
// SMTP message headers
$Sender.SendCRLF MAIL FROM:$from
$Sender.SendCRLF RCPT TO:$to
// body
$Sender.SendCRLF DATA
$Sender.SendCRLF From: $from
$Sender.SendCRLF To: $to
$Sender.SendCRLF Subject: Mail sent from ViRC
$Sender.SendCRLF
$Sender.SendCRLF This message was brought to you by TSockets.
// end message
$Sender.SendCRLF .
$Sender.SClose
EndAlias
// OnErrorOccurred event handler
Alias SMTP_ERROROCCURRED
// just show a message box
MessageBox Socket error $Error occurred ($Msg)
EndAlias
Multiple Interpreters
=====================
ViRC has a script interpreter for each server, and a global script interpreter
for action that isn't associated with a server. The global interpreter runs
ViRC.lib, <OnStart>, <OnClose>, main menu items, and DCC chat commands/events/
popups. The server interpreters run code for any command, event, or popup
that occurs in the server, channel, or query windows. OVS event handlers are
run by the interpreter that set them.
Window names and OVS object handles are only available to the interpreter
they belong to (although DCC chat window names can be used everywhere). This
means that if you create objects that need to be used from more than one
server, it's best to create them on the global interpreter.
Using BCONV
===========
The included BCONV utility can be used to easily create forms in OVS. BCONV
translates form (.dfm) files created with Delphi into script files that can
be used without much modification.
BCONV can be used two ways. The first way reads a form from a binary DFM
file:
C:\ViRC> bconv myform.dfm myform.vsc
The second way extracts a form resource from any program compiled with
Delphi:
C:\ViRC> bconv ViRC.exe/TCONFIGFORM configform.vsc
The part before the slash is the EXE or DLL filename; the part after is the
resource name. To get a list of resources, use a question mark for the name:
C:\ViRC> bconv ViRC.exe/?
Note that BCONV is not perfect, and many forms cannot be converted to OVS
that will work in ViRC. For example, BCONV doesn't make valid code from
forms that have controls with collections (like status bars), doesn't put a
dollar sign in front of the component name for properties that contain
objects, and ignores properties that contain binary data (like icons). Always
read over the output to ensure that it is valid.